docs: fix phase READMEs and STATE.md — add full scope/plan to phases 9-15, fix stale last-commit field

.paul/phases/12-onprem-report-pull/README.md

@@ -1,9 +1,66 @@
 # Phase 12: On-Prem Monthly Report Pull
 
 **Status:** Not started
+**Depends on:** Phase 11 (Monthly Reports)
 
 ## Goal
-Hub pulls attendance data from each TapTrack instance for monthly reports.
 
-## Plans
-- [ ] TBD — run /paul:plan when Phase 11 is complete
+Hub pulls attendance summary data from each on-prem TapTrack instance on the 1st of the month
+to populate monthly report data. Fallback: if on-prem is unreachable, report shows
+"attendance data unavailable" for that section.
+
+## Planned Scope
+
+### On-Prem Side (TapTrack — separate repo, documented here for reference)
+
+**New endpoint on TapTrack on-prem:**
+`GET /api/hub/monthly-report?key={license_key}&month={YYYY-MM}`
+
+Response:
+```json
+{
+  "month": "2026-02",
+  "total_students": 450,
+  "school_days": 20,
+  "present_days_total": 8100,
+  "absent_days_total": 900,
+  "late_days_total": 200,
+  "avg_attendance_rate": 90.0,
+  "sms_sent": 342
+}
+```
+
+### Hub Side
+
+**`school_monthly_stats` table** (new model)
+- `id`, `school_id`, `report_month` (YYYY-MM date), `total_students`, `school_days`,
+  `present_days_total`, `absent_days_total`, `late_days_total`, `avg_attendance_rate`,
+  `sms_sent`, `pulled_at`, `pull_status` (success/failed/unavailable)
+
+**New Celery task: `reports.pull_monthly_stats`**
+- Runs on the 1st at 5:00am (before `send_monthly_reports` at 7:00am)
+- For each active school with a `last_seen_ip` and `hub_base_url`:
+  - GET `{school.hub_base_url}/api/hub/monthly-report?key={license_key}&month={YYYY-MM}`
+  - On success: upsert `school_monthly_stats` with pull_status=success
+  - On failure/timeout: create record with pull_status=unavailable
+- Timeout: 10 seconds per school
+
+**School model** — add `hub_base_url: str | None` column (the on-prem instance URL)
+- Set automatically from `last_seen_ip` or configured manually by super admin
+
+**Super admin UI** — `hub_base_url` field in SchoolDetailPage edit panel
+
+### Frontend
+
+No new pages needed — data surfaces through monthly reports (Phase 11).
+
+**SchoolDetailPage.vue** — show `hub_base_url` field in school info + edit modal
+
+## Key Files to Create/Modify
+
+- `backend/app/models/school.py` — add `hub_base_url` column
+- `backend/app/models/report.py` — add `SchoolMonthlyStats` model
+- `backend/app/tasks/reports.py` — add `pull_monthly_stats` task
+- `backend/app/worker.py` — schedule pull task at 5am on 1st
+- `backend/migrations/versions/004_school_monthly_stats.py` (new)
+- `frontend/src/pages/SchoolDetailPage.vue` — hub_base_url field