shell-docs: document optional schema migrations Step in self-hosting

The Helm chart supports running schema migrations as a pre-install Job
(disabled by default). Document the opt-in path and the verification
behavior so operators can decide whether to enable it.

Author: samjulien

showcase/shell-docs/src/content/docs/premium/self-hosting.mdx

@@ -191,6 +191,19 @@ Before starting, make sure the following are in place. The [How the Intelligence
     The exact Secret names referenced in your values file must match whatever you create.
   </Step>
 
+  <Step>
+    ### (Optional) Enable schema migrations
+
+    The chart can run database schema migrations as a pre-install `Job`. This is **disabled by default** (`migrations.enabled: false`). If you want the chart to apply migrations for you on install, set the following in `my-values.yaml`:
+
+    ```yaml title="my-values.yaml"
+    migrations:
+      enabled: true
+    ```
+
+    With this enabled, `helm install` blocks the rollout until the migrations Job reports `Completed`. Leave it disabled if you manage schema migrations out-of-band (for example, via your existing CI/CD or DBA pipeline).
+  </Step>
+
   <Step>
     ### Install the chart
 
@@ -203,7 +216,7 @@ Before starting, make sure the following are in place. The [How the Intelligence
       --timeout 10m
     ```
 
-    `--wait` blocks until the `Deployments` report healthy replicas; `--timeout 10m` allows enough time for image pulls and the initial database migration job.
+    `--wait` blocks until the `Deployments` report healthy replicas; `--timeout 10m` allows enough time for image pulls and (if you enabled it in the previous step) the initial database migration job.
   </Step>
 
   <Step>
@@ -216,7 +229,7 @@ Before starting, make sure the following are in place. The [How the Intelligence
     kubectl get ingress -n copilot-intelligence
     ```
 
-    You should see `app-api`, `app-frontend`, and — if enabled — `realtime-gateway` pods running. The migrations `Job` will appear as `Completed`.
+    You should see `app-api`, `app-frontend`, and — if enabled — `realtime-gateway` pods running. If you opted into migrations (`migrations.enabled: true`, see the values step above), the migrations `Job` will also appear as `Completed`; if you left migrations disabled, no Job is created.
 
     Confirm the API health check reports `ok`: