docs(m4): add core data actors with two example scenarios

docs/MILESTONES/M4/planning/m4-core-data-actors-scenarios.md

@@ -0,0 +1,82 @@
+# M4 Core Data Actors and Example Scenarios
+
+Status: Working draft  
+Date: 2026-02-25  
+Owner: Technical Lead
+
+## 1) Core data actors
+1. `Tenant`: staffing company boundary and data isolation root.
+2. `User`: human identity that signs in.
+3. `TenantMembership`: user role/context inside one tenant.
+4. `Business`: client account served by the tenant.
+5. `Vendor`: supplier account that can fulfill staffing demand.
+6. `Workforce/Staff`: worker profile used for assignment and attendance.
+7. `StakeholderType`: typed category (`buyer`, `operator`, `vendor_partner`, `workforce`, `partner`).
+8. `StakeholderProfile`: typed actor record inside a tenant.
+9. `StakeholderLink`: relationship between stakeholder profiles.
+
+## 2) Minimal actor map
+
+```mermaid
+flowchart LR
+  T["Tenant"] --> TM["TenantMembership"]
+  U["User"] --> TM
+  T --> B["Business"]
+  T --> V["Vendor"]
+  U --> S["Workforce/Staff"]
+  T --> SP["StakeholderProfile"]
+  ST["StakeholderType"] --> SP
+  SP --> SL["StakeholderLink"]
+  B --> O["Orders/Shifts"]
+  V --> O
+  S --> O
+```
+
+## 3) Scenario A: Legendary Event Staffing
+Context:
+1. Tenant is `Legendary Event Staffing and Entertainment`.
+2. Business is `Google Mountain View Cafes`.
+3. Legendary uses its own workforce, and can still route overflow to approved vendors.
+
+```mermaid
+sequenceDiagram
+  participant Tenant as "Tenant (Legendary)"
+  participant Biz as "Business (Google Cafes)"
+  participant Ops as "User + TenantMembership (Ops Lead)"
+  participant Staff as "Workforce/Staff (Barista Ana)"
+  participant Link as "StakeholderLink"
+
+  Biz->>Ops: "Create staffing request"
+  Ops->>Tenant: "Create order under tenant scope"
+  Ops->>Link: "Resolve business-to-vendor/workforce relationships"
+  Ops->>Staff: "Assign qualified worker"
+  Staff-->>Ops: "Clock in/out and complete shift"
+  Ops-->>Biz: "Invoice/report generated with audit trail"
+```
+
+## 4) Scenario B: Another tenant (external vendor-heavy)
+Context:
+1. Tenant is `Peakline Events`.
+2. Business is `NVIDIA Campus Dining`.
+3. Peakline primarily fulfills demand through external approved vendors.
+
+```mermaid
+sequenceDiagram
+  participant Tenant as "Tenant (Peakline Events)"
+  participant Biz as "Business (NVIDIA Dining)"
+  participant Ops as "User + TenantMembership (Coordinator)"
+  participant Vendor as "Vendor (Metro Staffing)"
+  participant Staff as "Workforce/Staff (Vendor worker)"
+
+  Biz->>Ops: "Request recurring event staffing"
+  Ops->>Tenant: "Create recurring order"
+  Ops->>Vendor: "Dispatch required roles"
+  Vendor->>Staff: "Provide available workers"
+  Staff-->>Ops: "Attendance and completion events"
+  Ops-->>Biz: "Settlement + performance reports"
+```
+
+## 5) Why this model scales
+1. New stakeholders can be added through `StakeholderType` and `StakeholderProfile` without changing core order/shift tables.
+2. Multi-tenant isolation stays strict because all critical records resolve through `Tenant`.
+3. Legendary and non-Legendary operating models both fit the same structure.