docs(deploy): the demo data sequence a fresh database needs

DEPLOYMENT.md

@@ -215,6 +215,60 @@ none of that risk. **Recommendation: keep the jar.**
 - [ ] The browser network tab shows `/api/v1/udyam/...` calls returning 200, not HTML
 - [ ] `UDYAM_JWT_SECRET` is not the committed default
 
+## Populating a fresh database — the demo sequence
+
+The seeder writes the portfolio, the ledger and the forecasts. It does **not** write
+loan history, UPI inflows or the no-feed price series: those are admin calls, so a fresh
+database comes up without them and several screens look thinner than they should.
+
+Run these once, in order, after the seeder's final log line:
+
+```bash
+BASE=http://localhost:8082/api/v1/udyam
+TOKEN=<a supervisor token from POST $BASE/auth/login>
+
+# 1. DPD history — 24 monthly snapshots per loan, stamped SEEDED_HISTORY
+curl -X POST -H "Authorization: Bearer $TOKEN" "$BASE/admin/loan-history/generate?months=24"
+
+# 2. UPI inflows — 26 weeks per enterprise, stamped SIMULATED.
+#    Stands in for Account Aggregator data until Sahamati FIU registration exists.
+curl -X POST -H "Authorization: Bearer $TOKEN" "$BASE/admin/upi/simulate"
+
+# 3. Prices for the commodities with no API anywhere — milk, egg, fodder, sugarcane
+curl -X POST -H "Authorization: Bearer $TOKEN" "$BASE/admin/ingestion/simulate/no-feed"
+
+# 4. Derive the features, then score against them
+curl -X POST -H "Authorization: Bearer $TOKEN" "$BASE/admin/features/compute"
+curl -X POST -H "Authorization: Bearer $TOKEN" "$BASE/admin/scoring/run"
+```
+
+Verify with the coverage endpoints, both of which report synthetic and real separately:
+
+```bash
+curl -H "Authorization: Bearer $TOKEN" "$BASE/admin/loan-history/coverage"
+curl -H "Authorization: Bearer $TOKEN" "$BASE/admin/upi/coverage"
+```
+
+### All of it is labelled, and none of it can overwrite a fact
+
+Every row written above carries its provenance in the table — `SEEDED_HISTORY` on loan
+records, `SIMULATED` on UPI and price rows — and the simulators refuse to overwrite a
+non-simulated row even when asked to. Real data can land beside this at any time and
+stays distinguishable forever. The console surfaces the distinction rather than leaving
+it to a slide.
+
+Two consequences to state out loud rather than discover later:
+
+- **`loan-history/coverage` reports `trainable: false`** while no real extract exists,
+  and that is correct. The seeder derives DPD from the risk band and the UPI simulator
+  derives inflow drift from the same band, so a model trained on this would learn the
+  seeder's own rule and validate beautifully while knowing nothing. The synthetic data
+  is here to exercise the pipeline and fill the console, not to train.
+- **This sequence does not give you the real mandi price history.** Steps 1–3 are
+  synthetic; the three-year Agmarknet backfill is real data and needs `DATAGOV_API_KEY`
+  plus a long one-off run, or a dump of a database that already has it. Without it
+  `price_z_score` has no seasonal mean and TW-05 stays quiet.
+
 ## What is deliberately off
 
 `udyam.ingestion.enabled` is `false`, so a demo boot never calls a government endpoint,