feat: add Party management API with RESTful endpoints and comprehensive documentation

- Introduce Party model with lifecycle states (draft, published, canceled, sold_out)
- Add RESTful API endpoints under /api/v1/parties for CRUD operations
- Create ApiController base with API key authentication
- Implement comprehensive code comments across models and controllers
- Add database migration for parties table with proper indexes
- Configure API routes with namespaced versioning

app/models/party.rb

@@ -0,0 +1,40 @@
+# Party model representing nightlife events and parties
+# Manages event details, location data, and publication state
+class Party < ApplicationRecord
+  # Define states for party lifecycle management
+  # draft: Initial state when party is being created
+  # published: Party is visible to public and can be discovered
+  # canceled: Party has been canceled by organizer
+  # sold_out: Party has reached capacity and tickets are no longer available
+  enum state: {
+    draft: 0,
+    published: 1,
+    canceled: 2,
+    sold_out: 3
+  }, default: :draft
+
+  # Validations for party attributes
+  # Basic information
+  validates :name, presence: true, length: { minimum: 3, maximum: 100 }
+  validates :description, presence: true, length: { minimum: 10, maximum: 1000 }
+  validates :state, presence: true, inclusion: { in: states.keys }
+  
+  # Venue information
+  validates :venue_name, presence: true, length: { maximum: 100 }
+  validates :venue_address, presence: true, length: { maximum: 200 }
+  
+  # Geographic coordinates for map display
+  validates :latitude, presence: true, numericality: {
+    greater_than_or_equal_to: -90,
+    less_than_or_equal_to: 90
+  }
+  validates :longitude, presence: true, numericality: {
+    greater_than_or_equal_to: -180,
+    less_than_or_equal_to: 180
+  }
+
+  # Scopes for querying parties with common filters
+  scope :featured, -> { where(featured: true) }  # Get featured parties for homepage
+  scope :published, -> { where(state: :published) }  # Get publicly visible parties
+  scope :search_by_name, ->(query) { where("name ILIKE ?", "%#{query}%") }  # Search by name (case-insensitive)
+end