docs: write down how the energy/CO2 metrics actually work (#3)

The calculation lived only in code comments. Adds docs/energy-metrics.md and wires it
into the README, per the issue's proposed scope. No calculation changes.

Contents: the input (completion_tokens, output tokens only, grouped on model_group)
and why output-only understates total compute; the factor table with its three
provenance tiers (measured / same-family / estimated) and the fact that the tiers are
never exposed; the formulas; NULL-not-zero and the reason (the first backfill claimed
every day used no energy); the implied-grid-intensity tripwire and the 1000x carbon
error it exists to catch; the 03:15 schedule and that --backfill REWRITES history.

States plainly what is measured and what is not: GreenPT is measured, glm-5.3 is
assumed from its flash sibling, and all Tinfoil and Regolo traffic currently falls to
the proxy estimate — with the consequence that the 250 gCO2e/kWh proxy OVERSTATES
Regolo, which runs on renewable energy.

README: "Two jobs" -> "Three", the metrics_snapshot task documented, and a short
Energy & carbon metrics subsection linking the new doc. Also corrects "listing both
tasks" in the post-change verification step.

README.md

@@ -93,7 +93,7 @@ points. Remaining work before production:
 
 ## Scheduled tasks (scheduler addon)
 
-Two jobs run inside the container via `CloudronManifest.json` → `addons.scheduler`:
+Three jobs run inside the container via `CloudronManifest.json` → `addons.scheduler`:
 
 - **membership_sweep** (nightly 3am) — `sweep.sh` calls the portal's own
   `/admin/sweep` (auth: `X-Admin-Token` = `WEBHOOK_TOKEN`) to reconcile members
@@ -105,7 +105,25 @@ Two jobs run inside the container via `CloudronManifest.json` → `addons.schedu
   files to Open WebUI (`OWUI_API_KEY`), attaches them to the shared knowledge
   collection (`DOCS_KNOWLEDGE_ID`), reindexes, and re-grants the members group.
   State persists in `/app/data/rag_refresh_state.json`.
+- **metrics_snapshot** (nightly 3:15am) — `metrics_snapshot.py` records one row per
+  day into the `metrics_daily` table: members, newsletter subscribers, Matrix
+  membership, spend, request counts, and energy/CO₂. A source that cannot be read
+  yields NULL for that metric rather than a zero. `--backfill` rebuilds history
+  idempotently. Methodology: [Energy and carbon metrics](docs/energy-metrics.md).
 
 Verify after any manifest change: the deploy log must show
-`setupAddons: ... scheduler ...` listing both tasks, and each script must
+`setupAddons: ... scheduler ...` listing all three tasks, and each script must
 succeed when run manually inside the container.
+
+### Energy & carbon metrics
+
+The daily snapshot also computes energy (Wh) and carbon (gCO₂e) from output tokens,
+using per-model factors whose provenance varies: measured for GreenPT, assumed equal
+for one sibling model, and an explicit order-of-magnitude estimate for providers that
+disclose nothing. Only output tokens count, and a day with no measured tokens is
+recorded as NULL rather than zero.
+
+[Energy and carbon metrics](docs/energy-metrics.md) documents the factor table, the
+formulas, the tripwire that catches unit errors, the schedule, and — most importantly —
+which parts are measurements and which are estimates. What members are told is in
+`co-op/docs/energy.md`.