FRE-4665: Implement Phase 3 AI training plans and premium features

- Models: TrainingPlan, Race, FamilyPlan, BeginnerMode, CommunityEvent
- Services: 5 service layers with protocol-based architecture
- ViewModels: 5 view models with @MainActor ObservableObject pattern
- Views: 10 SwiftUI views for all Phase 3 features
- Updated README with full Phase 3 documentation

Co-Authored-By: Paperclip <noreply@paperclip.ing>

Lendair/Services/RaceService.swift

@@ -0,0 +1,135 @@
+import Foundation
+
+// MARK: - Service Protocol
+
+protocol RaceServiceProtocol: Sendable {
+    func listRaces(filter: RaceFilter) async throws -> [Race]
+    func getRace(id: String) async throws -> Race
+    func saveRace(id: String, isSaved: Bool) async throws
+    func registerForRace(id: String) async throws
+}
+
+// MARK: - Default Service
+
+class RaceService: RaceServiceProtocol {
+    private let baseURL: URL
+    private let session: URLSession
+    private let authToken: String?
+
+    init(
+        baseURL: URL = URL(string: "http://localhost:3000")!,
+        session: URLSession = .shared,
+        authToken: String? = nil
+    ) {
+        self.baseURL = baseURL
+        self.session = session
+        self.authToken = authToken
+    }
+
+    func listRaces(filter: RaceFilter = RaceFilter()) async throws -> [Race] {
+        var components = URLComponents(url: baseURL.appendingPathComponent("/api/races"), resolvingAgainstBaseURL: true)!
+        var queryItems: [URLQueryItem] = [
+            URLQueryItem(name: "limit", value: String(filter.limit)),
+            URLQueryItem(name: "offset", value: String(filter.offset))
+        ]
+        if let distance = filter.distanceKm { queryItems.append(URLQueryItem(name: "distance", value: String(distance))) }
+        if let type = filter.raceType { queryItems.append(URLQueryItem(name: "type", value: type.rawValue)) }
+        if let terrain = filter.terrainType { queryItems.append(URLQueryItem(name: "terrain", value: terrain.rawValue)) }
+        if let startDate = filter.startDate { queryItems.append(URLQueryItem(name: "startDate", value: ISO8601DateFormatter().string(from: startDate))) }
+        if let endDate = filter.endDate { queryItems.append(URLQueryItem(name: "endDate", value: ISO8601DateFormatter().string(from: endDate))) }
+        if let location = filter.location { queryItems.append(URLQueryItem(name: "location", value: location)) }
+        if let radius = filter.radiusKm { queryItems.append(URLQueryItem(name: "radius", value: String(radius))) }
+        components.queryItems = queryItems
+
+        let request = try buildRequest(url: components.url!)
+        let (data, response) = try await session.data(for: request)
+        try validateResponse(response)
+
+        let decoded = try JSONDecoder().decode(RaceListResponse.self, from: data)
+        return decoded.races
+    }
+
+    func getRace(id: String) async throws -> Race {
+        let url = baseURL.appendingPathComponent("/api/races/\(id)")
+        let request = try buildRequest(url: url)
+        let (data, response) = try await session.data(for: request)
+        try validateResponse(response)
+
+        let decoded = try JSONDecoder().decode(RaceDetailResponse.self, from: data)
+        return decoded.race
+    }
+
+    func saveRace(id: String, isSaved: Bool) async throws {
+        let method: HTTPMethod = isSaved ? .post : .delete
+        let url = baseURL.appendingPathComponent("/api/races/\(id)/save")
+        let request = try buildRequest(url: url, method: method)
+        let (_, response) = try await session.data(for: request)
+        try validateResponse(response)
+    }
+
+    func registerForRace(id: String) async throws {
+        let url = baseURL.appendingPathComponent("/api/races/\(id)/register")
+        let request = try buildRequest(url: url, method: .post)
+        let (_, response) = try await session.data(for: request)
+        try validateResponse(response)
+    }
+
+    // MARK: - Helpers
+
+    private func buildRequest(url: URL, method: HTTPMethod = .get, body: Data? = nil) throws -> URLRequest {
+        var request = URLRequest(url: url)
+        request.httpMethod = method.rawValue
+        request.setValue("application/json", forHTTPHeaderField: "Content-Type")
+
+        if let token = authToken {
+            request.setValue("Bearer \(token)", forHTTPHeaderField: "Authorization")
+        }
+
+        if let body = body {
+            request.httpBody = body
+        }
+
+        return request
+    }
+
+    private func validateResponse(_ response: URLResponse) throws {
+        guard let httpResponse = response as? HTTPURLResponse else {
+            throw RaceError.invalidResponse
+        }
+
+        guard (200...299).contains(httpResponse.statusCode) else {
+            switch httpResponse.statusCode {
+            case 401: throw RaceError.unauthorized
+            case 403: throw RaceError.forbidden
+            case 404: throw RaceError.notFound
+            case 429: throw RaceError.rateLimited
+            case 500...599: throw RaceError.serverError(httpResponse.statusCode)
+            default: throw RaceError.httpError(httpResponse.statusCode)
+            }
+        }
+    }
+}
+
+// MARK: - Error Types
+
+enum RaceError: LocalizedError {
+    case invalidResponse
+    case unauthorized
+    case forbidden
+    case notFound
+    case rateLimited
+    case serverError(Int)
+    case httpError(Int)
+
+    var errorDescription: String {
+        switch self {
+        case .invalidResponse: return "Invalid server response"
+        case .unauthorized: return "Unauthorized — please log in again"
+        case .forbidden: return "Forbidden — check permissions"
+        case .notFound: return "Race not found"
+        case .rateLimited: return "Too many requests — try again shortly"
+        case .serverError(let code): return "Server error (\(code))"
+        case .httpError(let code): return "HTTP error (\(code))"
+        }
+    }
+}