docs: add comprehensive code comments, update README and TASKS, create training and troubleshooting guides

- Add JSDoc comments to API routes and business logic functions
- Update README.md with Phase 2 status and deployment/production notes
- Enhance TASKS.md with estimated timelines and dependencies
- Create docs/STAFF_TRAINING.md for team onboarding
- Create docs/CLIENT_ONBOARDING.md for customer experience
- Create docs/OPERATIONAL_PROCEDURES.md for daily operations
- Create docs/TROUBLESHOOTING.md for common setup issues
- Fix TypeScript errors in hq/page.tsx

app/api/aperture/dashboard/route.ts

@@ -1,6 +1,9 @@
 import { NextRequest, NextResponse } from 'next/server'
 import { supabaseAdmin } from '@/lib/supabase/client'
 
+/**
+ * @description Fetches bookings with filters for dashboard view
+ */
 export async function GET(request: NextRequest) {
   try {
     const { searchParams } = new URL(request.url)

app/api/aperture/permissions/route.ts

@@ -37,6 +37,9 @@ const mockPermissions = [
   }
 ]
 
+/**
+ * @description Retrieves permissions data for different roles
+ */
 export async function GET() {
   return NextResponse.json({
     success: true,
@@ -44,6 +47,9 @@ export async function GET() {
   })
 }
 
+/**
+ * @description Toggles a specific permission for a role
+ */
 export async function POST(request: NextRequest) {
   const { roleId, permId } = await request.json()
 

app/api/aperture/reports/payments/route.ts

@@ -1,6 +1,9 @@
 import { NextRequest, NextResponse } from 'next/server'
 import { supabaseAdmin } from '@/lib/supabase/client'
 
+/**
+ * @description Fetches recent payments report
+ */
 export async function GET() {
   try {
     // Get recent payments (assuming bookings with payment_intent_id are paid)

app/api/aperture/reports/payroll/route.ts

@@ -1,6 +1,9 @@
 import { NextRequest, NextResponse } from 'next/server'
 import { supabaseAdmin } from '@/lib/supabase/client'
 
+/**
+ * @description Fetches payroll report for staff based on recent bookings
+ */
 export async function GET() {
   try {
     // Get staff and their bookings this week

app/api/aperture/reports/sales/route.ts

@@ -1,6 +1,9 @@
 import { NextRequest, NextResponse } from 'next/server'
 import { supabaseAdmin } from '@/lib/supabase/client'
 
+/**
+ * @description Fetches sales report including total sales, completed bookings, average service price, and sales by service
+ */
 export async function GET() {
   try {
     // Get total sales

app/api/aperture/resources/route.ts

@@ -1,6 +1,9 @@
 import { NextRequest, NextResponse } from 'next/server'
 import { supabaseAdmin } from '@/lib/supabase/client'
 
+/**
+ * @description Retrieves active resources, optionally filtered by location
+ */
 export async function GET(request: NextRequest) {
   try {
     const { searchParams } = new URL(request.url)

app/api/aperture/staff/route.ts

@@ -1,6 +1,9 @@
 import { NextRequest, NextResponse } from 'next/server'
 import { supabaseAdmin } from '@/lib/supabase/client'
 
+/**
+ * @description Gets available staff for a location and date
+ */
 export async function GET(request: NextRequest) {
   try {
     const { searchParams } = new URL(request.url)

app/api/aperture/staff/schedule/route.ts

@@ -1,6 +1,9 @@
 import { NextRequest, NextResponse } from 'next/server'
 import { supabaseAdmin } from '@/lib/supabase/client'
 
+/**
+ * @description Retrieves staff availability schedule with optional filters
+ */
 export async function GET(request: NextRequest) {
   try {
     const { searchParams } = new URL(request.url)
@@ -60,6 +63,9 @@ export async function GET(request: NextRequest) {
   }
 }
 
+/**
+ * @description Creates or updates staff availability
+ */
 export async function POST(request: NextRequest) {
   try {
     const body = await request.json()
@@ -145,6 +151,9 @@ export async function POST(request: NextRequest) {
   }
 }
 
+/**
+ * @description Deletes staff availability by ID
+ */
 export async function DELETE(request: NextRequest) {
   try {
     const { searchParams } = new URL(request.url)