feat: improve documentation, tests, and examples

[allisson]

This commit significantly enhances the go-pglock package with comprehensive documentation, improved test coverage, and practical examples for common distributed locking patterns.

Documentation improvements:

• Rewrite README.md with 10 detailed examples covering real-world use cases including leader election, task processing, resource pools, and migrations
• Add QUICKREF.md with concise API reference, patterns, and troubleshooting
• Add examples/README.md with detailed guide for running example programs
• Enhance all Go doc strings in lock.go following best practices with comprehensive descriptions of behavior, parameters, and edge cases
• Add package-level documentation explaining PostgreSQL advisory locks

Test improvements:

• Add 12 comprehensive test cases covering:
  • Basic lock acquisition and release
  • Lock stacking behavior (multiple acquisitions)
  • Context cancellation and timeout handling
  • Concurrent lock attempts with race detection
  • Blocking vs non-blocking behavior
  • Lock cleanup via Close()
  • Error cases and edge conditions
• Improve test helpers with t.Helper(), require assertions, and better error messages
• Add proper test skipping when DATABASE_URL is not set
• All tests pass with race detector enabled

Example programs:

• Add 5 complete, runnable example programs demonstrating:
  • basic/ - Simple lock acquire/release pattern
  • workers/ - Concurrent workers coordinating access
  • leader-election/ - Cluster leadership election
  • timeout/ - Context timeout and cancellation
  • task-processing/ - Distributed task coordination
• All examples compile successfully and include proper error handling

Development tooling:

• Add docker-compose.yml for easy PostgreSQL test database setup
• Enhance Makefile with test-race, test-coverage, docker-up, docker-down, and test-local targets for improved developer experience

The documentation now provides clear guidance from basic usage to advanced patterns, with 10 real-world examples, troubleshooting guides, and best practices. Test coverage includes comprehensive scenarios with proper concurrency testing and edge case handling.