Add feature specs for booking platform requirements

Update availability, lesson-booking, and user-roles docs and add specs
for offerings, group classes, registration questions, versioned policies,
Stripe payments (with e-transfer/comp overrides and receipts), and
monthly per-instructor payment reporting. Tracked in issues #1-#9.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs/features/availability-management.md

@@ -1,39 +1,57 @@
 # Feature: Availability Management
 
 ## Overview
-Instructors define date/time windows during which they are available for lessons. Students book from these windows.
+Instructors define date/time windows during which they are available for private lessons. Students book from these windows. Windows carry a lesson length and may be generated as a weekly-recurring series.
 
 ## Data Model — `{prefix}us_availability`
 
-| Column         | Type             | Notes                                        |
-|----------------|------------------|----------------------------------------------|
-| `id`           | BIGINT UNSIGNED  | Primary key                                  |
-| `instructor_id`| BIGINT UNSIGNED  | WordPress user ID                            |
-| `start_dt`     | DATETIME         | Slot start — stored as `Y-m-d H:i:s`        |
-| `end_dt`       | DATETIME         | Slot end — stored as `Y-m-d H:i:s`          |
-| `is_booked`    | TINYINT(1)       | 0 = available, 1 = booked                    |
-| `created_at`   | DATETIME         | Insertion time                               |
+| Column             | Type             | Notes                                                        |
+|--------------------|------------------|-------------------------------------------------------------|
+| `id`               | BIGINT UNSIGNED  | Primary key                                                 |
+| `instructor_id`    | BIGINT UNSIGNED  | WordPress user ID                                           |
+| `offering_id`      | BIGINT UNSIGNED  | Nullable FK → `us_offerings.id` (private-lesson type)       |
+| `start_dt`         | DATETIME         | Slot start — stored as `Y-m-d H:i:s`                        |
+| `end_dt`           | DATETIME         | Slot end — stored as `Y-m-d H:i:s`                          |
+| `duration_minutes` | SMALLINT         | Lesson length the window accommodates (e.g. 30, 60)         |
+| `is_booked`        | TINYINT(1)       | 0 = available, 1 = booked                                  |
+| `recurrence_group` | BIGINT UNSIGNED  | Nullable — weekly-recurring windows share one group id     |
+| `created_at`       | DATETIME         | Insertion time                                             |
+
+A window's `duration_minutes` is matched against the offering a student picks: a
+30-minute private offering can only be booked into a window whose
+`duration_minutes` accommodates it.
+
+## Weekly-Recurring Windows
+Instructors may generate a window weekly across a date range. Each occurrence is a
+separate row sharing one `recurrence_group` id, so a recurring set can be added or
+removed together while individual occurrences are still booked independently.
 
 ## Admin Interface
 Instructors access **My Availability** in wp-admin (`?page=us-availability`).
-- Add a slot: provide start and end datetime
+- Add a slot: provide start/end datetime, duration, and (optionally) a linked private-lesson offering
+- Add a weekly series: provide the weekday/time plus a date range
 - Delete a slot: only allowed if `is_booked = 0`
 
+## Public Calendar
+The front-end booking shortcode renders a month/week calendar of open windows,
+populated from `GET /availability`. Students can filter by instructor and by
+offering/duration before selecting a slot to register for.
+
 ## REST API
-| Method   | Endpoint                          | Permission              |
-|----------|-----------------------------------|-------------------------|
-| `GET`    | `/wp-json/us-scheduler/v1/availability`       | `book_lesson`           |
-| `POST`   | `/wp-json/us-scheduler/v1/availability`       | `manage_availability`   |
+| Method   | Endpoint                                      | Permission                         |
+|----------|-----------------------------------------------|------------------------------------|
+| `GET`    | `/wp-json/us-scheduler/v1/availability`       | `book_lesson`                      |
+| `POST`   | `/wp-json/us-scheduler/v1/availability`       | `manage_availability`              |
 | `DELETE` | `/wp-json/us-scheduler/v1/availability/{id}`  | `manage_availability` + slot owner |
 
-`GET` supports query params: `instructor_id`, `from` (datetime), `to` (datetime).
+`GET` supports query params: `instructor_id`, `offering_id`, `duration_minutes`, `from` (datetime), `to` (datetime).
 
 ## Implementation
-- Repository: `Unsupervised\Schedular\Data\AvailabilityRepository`
-- Model: `Unsupervised\Schedular\Model\AvailabilitySlot`
-- Admin controller: `Unsupervised\Schedular\Admin\AvailabilityController`
-- REST endpoint: `Unsupervised\Schedular\Api\AvailabilityEndpoint`
+- Repository: `Unsupervised\Schedular\Availability\AvailabilityRepository`
+- Model: `Unsupervised\Schedular\Availability\AvailabilitySlot`
+- Admin controller: `Unsupervised\Schedular\Availability\AvailabilityController`
+- REST endpoint: `Unsupervised\Schedular\Availability\AvailabilityEndpoint`
 
 ## Tests
-- `tests/Unit/Data/AvailabilityRepositoryTest.php`
-- `tests/Unit/Model/AvailabilitySlotTest.php`
+- `tests/Unit/Availability/AvailabilityRepositoryTest.php`
+- `tests/Unit/Availability/AvailabilitySlotTest.php`