docs: Update workflow docs

Author: spuerta10

.github/workflows/cd-base.yml

@@ -1,17 +1,24 @@
 # ===============================================
-# CI/CD Pipeline: Pull GHCR image -> Re-tag -> Push to DockerHub -> Deploy with Terraform
+# CI/CD Pipeline: Pull GHCR image -> Re-tag -> Push to DockerHub -> Deploy with Terraform -> Integration Tests -> Cleanup
 # ===============================================
 # Description:
-# This workflow takes a Docker image from GHCR (GitHub Container Registry) generated by a PR or push,
-# retags it with the DockerHub username, pushes it to DockerHub, and then deploys the latest image
-# to Cloud Run using Terraform. It also handles initial database table creation if necessary.
+# This workflow automates the deployment and testing of the register-ticket-api service.
+# It performs the following steps:
+#   1. Pulls a Docker image from GitHub Container Registry (GHCR).
+#   2. Retags the image with DockerHub username and pushes it to DockerHub.
+#   3. Deploys the application to GCP using Terraform.
+#   4. Populates the database with test records.
+#   5. Runs integration tests against the deployed environment.
+#   6. Cleans up test data and database objects (always runs except for local environments).
 #
 # Inputs:
-#   - deployment_env: Deployment environment (e.g., staging, production)
+#   - deployment_env: Deployment environment (e.g., local, staging, production)
 #   - image_uri: URI of the image in GHCR (e.g., ghcr.io/org/repo:tag)
 #
 # Outputs:
-#   - dockerhub_image: URI of the retagged image pushed to DockerHub
+#   - dockerhub_image: URI of the image pushed to DockerHub
+#   - db_host: Hostname/IP of the deployed PostgreSQL database
+#   - api_url: URL of the deployed API service
 # ===============================================
 
 on:
@@ -143,6 +150,9 @@ jobs:
                  -v ON_ERROR_STOP=1
           done
 
+  # -------------------------------------------------
+  # Job: Run integration tests
+  # -------------------------------------------------
   run-integration-tests:
     needs: deploy
     uses: ./.github/workflows/integration-tests.yml
@@ -152,6 +162,9 @@ jobs:
       api_url: ${{ needs.deploy.outputs.api_url }}
     secrets: inherit # pragma: allowlist secret
 
+  # -------------------------------------------------
+  # Job: Cleanup database
+  # -------------------------------------------------
   cleanup-database:
     needs: [deploy, run-integration-tests]
     environment: ${{ inputs.deployment_env }}